Why `fastpages`?

UPDATE: quatro

This blog was setup in 2021 using fastpages. Two years later my site’s layout broke and I couldn’t fix it by reverting to previous commits. Then I went to check if I can update utils running under the hood and discovered that fastpages are deprecated in favor on another notebook-based publishing tool quarto. After a deep sigh, I decided to migrate the blog to quatro instead of trying to fix the fastpages version. The majority of the work is taken care automatically, see this this migration guide. I’m putting down a list of things that didn’t work immediately, or that I had to spent some time looking for, just in case.

It’s really hard to type quatro instead of quarto or quadro when you are web searching.
To have a custom icon on top of your blog’s webpage include the following file in _quarto.yml
```
---
website:
  favicon: /path/to/image.png
---
```
If paths to your images do not work, try /path/image.png instead of path/image.png or vice-versa. Or see here ?.
You can specify the last time the post was modified by including date-modified: 'xxxx-xx-xx' in the metadata.
Again, I had a problem with numbering and referencing equations. And again, I found a github comment that solved the issue. Including
```
---
format:
  html:
    html-math-method: mathjax
    include-in-header:
      - text: |
          <script>
          window.MathJax = {
            tex: {
              tags: 'ams'
            }
          };
          </script>
 ---
```
in the blog’s notebook header solves the issue without any need to modify the standard latex labeling conventions. However, apparently this solution might break in the future.
To exclude posts from your ‘about’ page put listing: false in the about.qmd.

Problems not solved.

I could not figure out how to render preview images for blog posts properly. They typically have wrong size. It’s possible to configure height of preview images in _quarto.yml
```
---
listing:
    image-height: 150px
---
```
However, this will crop, not resize the image. Heuristically I found that when the images have certain proportion (approximately the a4 paper size wide side down) they render well enough. So I had to went back and resize canvas of all my preview images. Hope there is a good solution that I’ve missed.
fastpages provided a really nice automatic badge for opening the notebook in colab. I think there is no support for this yet in quatro, but you can generate the badge yourself.

I must say that so far I really like the preview tool of quarto. Just call

quarto preview

in the shell and you quickly get a local version of your blog that is instantly updated as you change something in the posts or settings, much better than the preview I had with fastpages. Apparently, you things can get even better than that by using a proper IDE to work with quarto, but here I can offer little advice.

I also recommend checking out this guide on how to setup a tweak a quatro blog.

Fastpages

After deciding to start a scientific blog I was looking for an appropriate technical solution. My main requirements were - Ease of set up. - Ease of writing posts. - Decent support of \(\LaTeX\). - Support of code snippets.

After some search I decided to try out fastpages. I have a very limited understanding of the stack that fastpages use, so I treat it as a magic box. The magic box was easy for me to install while other bullet points are addressed all at once since fastpages allows to generate a post from a jupyter notebook. Although jupyter notebook is not exactly my favorite \(\LaTeX\) editor it still much better than many other options and a good overall compromise. So essentially with fastpages you can write your posts in jupyter notebook, then commit to your github repository and the content will automatically be hosted at your domain on github pages.

Caveats

Following official installation worked smoothly for me. While customizing the blog further for my purposes there were several things that did not work right of the box of took some time to find out how to change:

Solved

I wanted to use numbered \(\LaTeX\) equations with hyperlinks, which are not easily supported. This comment solved my problem!
You need to edit _pages/about.md to customize the way your “about” page is displayed.
To customize the front page you need to edit index.html. This is literally written on the front page of your blog, but I have not noticed it for a while.
Initially a lot of troubleshooting is needed to get the appearance of the blog I wanted. Commiting and waiting for the online web page to set up is super-slow. Here is an official guide on how to setup a live preview of your blog locally. One minor point that was a problem for me is that the default local server for blog preview https://127.0.0.1:4000 was not correct. After running sudo make server one of the outputs that jekyll produces is Server address: http://0.0.0.0:4000/blog/ which was the correct address for the live preview of my blog.
You need to do some work to make your site appear in google search results. This manual is very helpful, but a bit outdated: some of the things like generating sitemap.xml are now automated and do not require additional work as described in that post.

Not solved

On the web page the display equations of \(\LaTeX\) have fluctuations in size which does not look good.